/**
 ******************************************************************************
 * @file           : psv.h
 * @brief          : Periodic Signal Validator Header
 ******************************************************************************
 * @attention
 *
 * Copyright (c) 2025 PSV Project
 * SPDX-License-Identifier: MIT
 *
 * 周期信号验证器 - 基于周期规律性检测信号质量
 *
 * 功能：区分真实周期信号和随机干扰
 * 原理：真实信号周期均匀（CV<0.1），干扰信号杂乱（CV>0.3）
 *
 * 应用场景：
 * - 流量传感器（涡街、涡轮、齿轮）
 * - 转速测量（电机、风扇、车轮）
 * - 心率监测（脉搏、ECG）
 * - 振动监测（压电传感器）
 *
 ******************************************************************************
 */

#ifndef __PSV_H
#define __PSV_H

#ifdef __cplusplus
extern "C" {
#endif

/* Includes ------------------------------------------------------------------*/
#include <stdint.h>
#include "psv_config.h"

/* Exported types ------------------------------------------------------------*/

/**
 * @brief   PSV返回值定义
 */
typedef enum
{
    PSV_VALID = 1,      /*!< 信号有效 */
    PSV_INVALID = 0     /*!< 信号无效（干扰） */
} PSV_Result_e;

/**
 * @brief   PSV统计信息
 */
typedef struct
{
    float cv;                   /*!< 当前变异系数 */
    float mean_period_us;       /*!< 平均周期（微秒） */
    float std_dev_us;           /*!< 标准差（微秒） */
    uint8_t sample_count;       /*!< 采样数量 */
    uint8_t is_locked;          /*!< 信号是否锁定 */
} PSV_Statistics_t;

/* Exported constants --------------------------------------------------------*/
/* Exported macro ------------------------------------------------------------*/
/* Exported variables --------------------------------------------------------*/

/* Exported functions --------------------------------------------------------*/

/* 初始化函数 */
void psv_init(void);                        /* 初始化PSV模块 */

/* 检测函数 */
uint8_t psv_check(uint32_t freq_hz);        /* 检测频率信号质量（返回1=有效，0=无效） */

/* 复位函数 */
void psv_reset(void);                       /* 复位检测状态 */

/* 统计函数 */
void psv_get_statistics(PSV_Statistics_t *stats);  /* 获取统计信息（用于调试） */

#ifdef __cplusplus
}
#endif

#endif /* __PSV_H */
